Mit DocuGenerate können Sie PDF- und Word-Dokumente direkt aus Ihrer Node.js-Anwendung erstellen. Diese Anleitung zeigt, wie Sie jede API-Methode ab Node.js 20 aufrufen. Die vollständige Liste der Parameter und Antworten finden Sie in der API-Referenz.
1. Authentifizierung
2. Vorlage erstellen
3. Vorlagen auflisten
4. Vorlage abrufen
5. Vorlage aktualisieren
6. Vorlage löschen
7. Dokument generieren
8. Dokumente auflisten
9. Dokument abrufen
10. Dokument aktualisieren
11. Dokument löschen
Jede Anfrage wird authentifiziert, indem Sie Ihren API-Schlüssel im Header Authorization senden. Speichern Sie den Schlüssel in einer Umgebungsvariable, statt ihn fest in Ihren Quellcode zu schreiben:
export DOCUGENERATE_API_KEY="YOUR-API-KEY"
Alle folgenden Beispiele verwenden diese beiden Konstanten. Da fetch bei HTTP-Fehlerstatus keine Ausnahme auslöst, prüft jedes Beispiel response.ok, bevor es die Antwort liest:
const API_URL = 'https://api.docugenerate.com/v1';
const API_KEY = process.env.DOCUGENERATE_API_KEY;
Wenn Ihr Konto Daten in einer anderen Region speichert, ersetzen Sie die Basis-URL durch den passenden regionalen Endpunkt, zum Beispiel https://api.eu.docugenerate.com/v1.
Um eine Vorlage zu erstellen, laden Sie die Vorlagendatei mit einer Anfrage an POST /template hoch. Dieser Endpunkt erfordert den Inhaltstyp multipart/form-data, den fetch zusammen mit der Multipart-Boundary automatisch setzt, wenn der Body ein FormData-Objekt ist:
import { readFile } from 'node:fs/promises';
const form = new FormData();
form.append('file', new Blob([await readFile('Business Letter.docx')]), 'Business Letter.docx');
form.append('name', 'Business Letter');
const response = await fetch(`${API_URL}/template`, {
method: 'POST',
headers: {
Authorization: API_KEY,
Accept: 'application/json'
},
body: form
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const template = await response.json();
console.log(template.id);
Setzen Sie den Header Content-Type nicht selbst, sonst fehlt die Boundary und die Anfrage schlägt fehl. Die Antwort enthält die neue Vorlage, einschließlich der automatisch in der Datei erkannten tags:
{
"enhanced_syntax": false,
"versioning_enabled": false,
"folder": [],
"tags": {
"valid": [
"Date",
"Name",
"Job Title",
"Company Name",
"Street Address",
"City",
"State",
"Zip Code",
"Email",
"Phone"
],
"invalid": []
},
"created": 1791055374301,
"updated": 1791055374301,
"name": "Business Letter",
"delimiters": {
"left": "[",
"right": "]"
},
"filename": "Business Letter.docx",
"format": ".docx",
"region": "eu",
"page_count": 1,
"image_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.png?alt=media&token=0ce64a4b-495a-426b-8783-42b479f7ae38",
"preview_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.pdf?alt=media&token=0b3939c7-824e-4979-9aca-ca4a87175cbf",
"template_uri": "https://firebasestorage.googleapis.com/v0/b/storage.eu.docugenerate.com/o/templates%2FuVE30i1427KQsYcED0bl%2FBusiness%20Letter.docx?alt=media&token=d37a4458-3620-48db-94b8-6ac46f0442ab",
"id": "uVE30i1427KQsYcED0bl"
}
Bewahren Sie die id der Vorlage auf, da Sie sie zum Generieren von Dokumenten benötigen. Die folgenden optionalen Parameter können ebenfalls an das Formular angehängt werden:
delimiters: Die Begrenzer zur Erkennung der Tags, als JSON-String gesendet, z. B. JSON.stringify({ left: '[', right: ']' }). Standardmäßig werden sie automatisch ermittelt.region: Wo die Vorlage und ihre generierten Dokumente gespeichert werden, entweder us, eu, uk oder au. Standardmäßig wird die Region des Kontos verwendet.enhanced_syntax: Auf true setzen, um verschachtelte Eigenschaften und logische oder mathematische Operatoren in den Tags zu verwenden.versioning_enabled: Auf true setzen, um beim Hochladen einer neuen Datei frühere Versionen zu behalten, sofern Ihr Plan dies erlaubt.folder: Der Ordner der Vorlage, von der Wurzel bis zur untersten Ebene. Fehlende Ordner werden automatisch erstellt.Um die Vorlage in einem Ordner abzulegen, hängen Sie für jede Ebene des Pfads ein folder-Feld an. Zum Beispiel, um sie im Ordner Letters > Business abzulegen:
form.append('folder', 'Letters');
form.append('folder', 'Business');
Eine Anfrage an GET /template gibt alle Vorlagen in Ihrem Konto zurück:
const response = await fetch(`${API_URL}/template`, {
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const templates = await response.json();
for (const template of templates) {
console.log(template.id, template.name);
}
Um nur die Vorlagen eines Ordners aufzulisten, wiederholen Sie den Abfrageparameter folder für jede Ebene des Pfads. Zum Beispiel, um die Vorlagen im Ordner Letters > Business aufzulisten:
const query = new URLSearchParams();
query.append('folder', 'Letters');
query.append('folder', 'Business');
const response = await fetch(`${API_URL}/template?${query}`, {
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
Es werden nur die Vorlagen zurückgegeben, die direkt in diesem Ordner liegen. Vorlagen in seinen Unterordnern sind nicht enthalten. Erfahren Sie mehr darüber, wie Sie mit der API Vorlagen in Ordnern organisieren.
Um eine einzelne Vorlage abzurufen, rufen Sie GET /template/{id} mit ihrer ID auf:
const templateId = 'bet2oQirk0pSd9ctH9Qu';
const response = await fetch(`${API_URL}/template/${templateId}`, {
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const template = await response.json();
console.log(template.tags.valid);
Das ist zum Beispiel nützlich, um vor dem Generieren von Dokumenten zu prüfen, welche Zusammenführungs-Tags die Vorlage erwartet.
Eine Anfrage an PUT /template/{id} aktualisiert eine Vorlage. Alle Parameter sind optional, senden Sie also nur die, die Sie ändern möchten. Zum Beispiel, um eine neue Version der Datei hochzuladen und die Vorlage umzubenennen:
import { readFile } from 'node:fs/promises';
const templateId = 'bet2oQirk0pSd9ctH9Qu';
const form = new FormData();
form.append('file', new Blob([await readFile('Business Letter v2.docx')]), 'Business Letter v2.docx');
form.append('name', 'Business Letter v2');
const response = await fetch(`${API_URL}/template/${templateId}`, {
method: 'PUT',
headers: {
Authorization: API_KEY,
Accept: 'application/json'
},
body: form
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const template = await response.json();
Wie beim Erstellen einer Vorlage muss der Body multipart/form-data sein, was zusammen mit der Multipart-Boundary automatisch gesetzt wird, wenn der Body ein FormData-Objekt ist. Neben file und name können die folgenden optionalen Parameter an das Formular angehängt werden:
delimiters: Die neuen Begrenzer, als JSON-String gesendet. Wenn sie angegeben werden, wird die Vorlage erneut analysiert, um die Zusammenführungs-Tags anhand der neuen Begrenzer zu erkennen. Wird ein neues file ohne delimiters hochgeladen, werden die aktuellen Begrenzer verwendet.region: Verschiebt die Vorlage in eine andere Region, entweder us, eu, uk oder au. Danach generierte Dokumente werden in der neuen Region gespeichert, während bestehende Dokumente in ihrer aktuellen Region bleiben.folder: Verschiebt die Vorlage in einen anderen Ordner, mit einem folder-Feld für jede Ebene des Pfads. Senden Sie '[]', um die Vorlage aus jedem Ordner herauszunehmen.enhanced_syntax: Auf true oder false setzen, um die erweiterte Syntax zu aktivieren oder zu deaktivieren.versioning_enabled: Auf true oder false setzen, um den Versionsverlauf zu aktivieren oder zu deaktivieren, sofern Ihr Plan dies erlaubt.Um eine Vorlage zu löschen, senden Sie eine Anfrage an DELETE /template/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:
const templateId = 'bet2oQirk0pSd9ctH9Qu';
const response = await fetch(`${API_URL}/template/${templateId}`, {
method: 'DELETE',
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
Sie generieren Dokumente mit einer Anfrage an POST /document, wobei Sie die template_id und die data übergeben, mit denen die Zusammenführungs-Tags ersetzt werden:
const response = await fetch(`${API_URL}/document`, {
method: 'POST',
headers: {
Authorization: API_KEY,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
template_id: 'bet2oQirk0pSd9ctH9Qu',
data: {
'Date': 'October 4, 2026',
'Name': 'Emily Carter',
'Job Title': 'Operations Manager',
'Company Name': 'Harbor Point Consulting',
'Street Address': '118 West Street',
'City': 'Annapolis',
'State': 'Maryland',
'Zip Code': '21405',
'Email': 'emily.carter@example.com',
'Phone': '(410) 555-0142'
},
output_format: '.pdf'
})
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const document = await response.json();
console.log(document.document_uri);
Die Antwort enthält die Eigenschaften des Dokuments:
{
"created": 1791125416372,
"template_id": "bet2oQirk0pSd9ctH9Qu",
"name": "Business Letter",
"format": ".pdf",
"data_length": 1,
"filename": "Business Letter.pdf",
"document_uri": "https://firebasestorage.googleapis.com/v0/b/storage.us.docugenerate.com/o/documents%2FiESelthRt4uaYQRTemrL%2FBusiness%20Letter.pdf?alt=media&token=c4b259ec-249b-4b35-a62f-6a8dc0da75f3",
"id": "iESelthRt4uaYQRTemrL"
}
Das output_format kann .docx (Standard), .pdf, .doc, .odt, .txt, .html, .png oder eine PDF/A-Version sein. Sie können außerdem mit merge_with PDF-Dateien am Ende des generierten Dokuments zusammenführen oder mit attach Anhänge hinzufügen.
Datei herunterladen
Die document_uri verweist auf die generierte Datei, die Sie herunterladen und auf der Festplatte speichern können:
import { writeFile } from 'node:fs/promises';
const file = await fetch(document.document_uri);
if (!file.ok) {
throw new Error(`Download failed with status ${file.status}`);
}
await writeFile(document.filename, Buffer.from(await file.arrayBuffer()));
Datei direkt empfangen
Wenn das Dokument nicht in der Cloud gespeichert werden soll, setzen Sie den Header Accept auf application/octet-stream. Die API antwortet dann mit der Binärdatei statt mit JSON:
import { writeFile } from 'node:fs/promises';
const response = await fetch(`${API_URL}/document`, {
method: 'POST',
headers: {
Authorization: API_KEY,
Accept: 'application/octet-stream',
'Content-Type': 'application/json'
},
body: JSON.stringify({
template_id: 'bet2oQirk0pSd9ctH9Qu',
data: {
'Date': 'October 4, 2026',
'Name': 'Emily Carter',
'Job Title': 'Operations Manager',
'Company Name': 'Harbor Point Consulting',
'Street Address': '118 West Street',
'City': 'Annapolis',
'State': 'Maryland',
'Zip Code': '21405',
'Email': 'emily.carter@example.com',
'Phone': '(410) 555-0142'
},
output_format: '.pdf'
})
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
await writeFile('Business Letter.pdf', Buffer.from(await response.arrayBuffer()));
console.log(response.headers.get('X-Document-Id'));
Batch-Dokumentgenerierung
Um mehrere Dokumente in einer Anfrage zu generieren, übergeben Sie ein Array von Objekten als data. Für jedes Objekt wird ein Dokument generiert:
const response = await fetch(`${API_URL}/document`, {
method: 'POST',
headers: {
Authorization: API_KEY,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
template_id: 'bet2oQirk0pSd9ctH9Qu',
data: [
{ 'Date': 'October 4, 2026', 'Name': 'Emily Carter', 'Job Title': 'Operations Manager', 'Company Name': 'Harbor Point Consulting', 'Street Address': '118 West Street', 'City': 'Annapolis', 'State': 'Maryland', 'Zip Code': '21405', 'Email': 'emily.carter@example.com', 'Phone': '(410) 555-0142' },
{ 'Date': 'October 4, 2026', 'Name': 'Daniel Brooks', 'Job Title': 'Logistics Coordinator', 'Company Name': 'Northfield Logistics', 'Street Address': '2400 South Lamar Boulevard', 'City': 'Austin', 'State': 'Texas', 'Zip Code': '78704', 'Email': 'daniel.brooks@example.com', 'Phone': '(512) 555-0187' }
],
output_format: '.pdf',
single_file: true,
page_break: true
})
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const document = await response.json();
Standardmäßig werden alle Dokumente in einer einzigen Datei zusammengefasst, mit einem Seitenumbruch nach jedem Dokument. Setzen Sie page_break auf false, um die Seitenumbrüche zu entfernen.
Wenn single_file auf false gesetzt ist, wird pro Datenobjekt eine Datei generiert, und alle Dateien werden in einem .zip-Archiv zusammengefasst. Verwenden Sie den Parameter name, um das Archiv zu benennen, und output_name mit Zusammenführungs-Tags, um jeder Datei einen dynamischen Namen zu geben, z. B. Letter for [Name]:
JSON.stringify({
template_id: 'bet2oQirk0pSd9ctH9Qu',
data: [...],
output_format: '.pdf',
single_file: false,
name: 'Business Letters',
output_name: 'Letter for [Name]'
})
Dadurch entsteht ein Archiv Business Letters.zip mit Letter for Emily Carter.pdf und Letter for Daniel Brooks.pdf. Die Zusammenführungs-Tags in output_name müssen dieselben Begrenzer wie die Vorlage verwenden.
Datendatei verwenden
Um viele Dokumente auf einmal aus einer Excel- oder CSV-Datei zu generieren, senden Sie die Datei in einer multipart/form-data-Anfrage. Für jede Zeile der Tabelle wird ein Dokument generiert. Wenn die Datei mehrere Tabellenblätter enthält, geben Sie mit dem Parameter sheet an, welches verwendet werden soll.
import { readFile } from 'node:fs/promises';
const form = new FormData();
form.append('template_id', 'bet2oQirk0pSd9ctH9Qu');
form.append('file', new Blob([await readFile('Data.xlsx')]), 'Data.xlsx');
form.append('output_format', '.pdf');
const response = await fetch(`${API_URL}/document`, {
method: 'POST',
headers: {
Authorization: API_KEY,
Accept: 'application/json'
},
body: form
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
Die Verwendung einer Datendatei ist eine weitere Form der Batch-Generierung, daher gelten dieselben Parameter, um die generierten Dokumente in einer einzigen Datei zusammenzufassen oder sie in einem .zip-Archiv mit einem eigenen Namen für jede Datei zu gruppieren.
Eine Anfrage an GET /document gibt die aus einer Vorlage generierten Dokumente zurück. Die ID der Vorlage wird im Abfrageparameter template_id übergeben:
const query = new URLSearchParams({ template_id: 'bet2oQirk0pSd9ctH9Qu' });
const response = await fetch(`${API_URL}/document?${query}`, {
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const documents = await response.json();
for (const document of documents) {
console.log(document.id, document.name, document.document_uri);
}
Um ein einzelnes Dokument abzurufen, rufen Sie GET /document/{id} mit seiner ID auf:
const documentId = 'iESelthRt4uaYQRTemrL';
const response = await fetch(`${API_URL}/document/${documentId}`, {
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const document = await response.json();
Eine Anfrage an PUT /document/{id} benennt ein Dokument um, da der Name die einzige Eigenschaft ist, die geändert werden kann:
const documentId = 'iESelthRt4uaYQRTemrL';
const response = await fetch(`${API_URL}/document/${documentId}`, {
method: 'PUT',
headers: {
Authorization: API_KEY,
Accept: 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({ name: 'Letter for Emily Carter' })
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}
const document = await response.json();
Um ein Dokument zu löschen, senden Sie eine Anfrage an DELETE /document/{id}. Die API antwortet bei Erfolg mit dem Status 204 No Content:
const documentId = 'iESelthRt4uaYQRTemrL';
const response = await fetch(`${API_URL}/document/${documentId}`, {
method: 'DELETE',
headers: {
Authorization: API_KEY,
Accept: 'application/json'
}
});
if (!response.ok) {
throw new Error(`DocuGenerate API error ${response.status}: ${await response.text()}`);
}